home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir31 / gusdelay.zip / GUSDELAY.TXT < prev    next >
Text File  |  1994-05-06  |  76KB  |  1,316 lines
  1. This is the documentation file for GusDelay version 1.0.
  2. Copyright (c) 1994 by David MacMahon - All rights reserved
  3.  
  4. TABLE OF CONTENTS
  5. =================
  6.  
  7. 0. LEGAL STUFF
  8. 1. INTRODUCTION
  9.    A) Features
  10.    B) Requirements
  11.    C) Guide to the manual
  12. 2. QUICK START INSTRUCTIONS
  13.    A) Starting GusDelay
  14.    B) Getting on-line help
  15.    C) Creating an echo
  16.    D) Creating reverberation
  17.    E) Creating surround sound
  18.    F) Recording to disk
  19. 3. COMMAND LINE REFERENCE
  20.    A) On-line help
  21.    B) Initial configuration file
  22.    C) Disk-only mode
  23.    D) Input selection
  24.    E) Output file
  25.    F) Sampling rate
  26.    G) Stereo mode
  27.    H) Look-up table file
  28.    I) Extra wait factor
  29.    J) Examples
  30. 4. RUNTIME COMMAND REFERENCE
  31.    A) On-line help
  32.    B) Activating, deactivating, and selecting voices
  33.    C) Changing the volume of the current voice
  34.    D) Changing the delay of the current voice
  35.    E) Changing the pan position (balance) of the current voice
  36.    F) Displaying voice information
  37.    G) Configuration files
  38.    H) Look-up tables
  39.    I) Recording to disk
  40.    J) Quitting GusDelay
  41. 5. THEORY OF OPERATION
  42.    A) Data Flow - Buffers, Buffers, and Buffers
  43.    B) Signal Flow - Channels, Tracks, and Voices
  44. 6. FILE FORMATS
  45.    A) Look-up table (LUT) files
  46.    B) Configuration files
  47.    C) Sound files
  48. 7. FUTURE ENHANCEMENTS
  49. A1. CONTACTING THE AUTHOR
  50. A2. TROUBLESHOOTING
  51.  
  52. ==============
  53. 0. LEGAL STUFF
  54. ==============
  55. Version 1.0 of GusDelay is shareware.  It is NOT free.  The copy of GusDelay 
  56. which you received is an unregistered copy.  You may use this unregistered 
  57. copy for 15 days to evaluate GusDelay.  If you continue to use the program 
  58. after the 15 day evaluation period you are required to register the program. 
  59. See the file REGISTER.TXT for registration instructions.  The shareware 
  60. concept is designed to let you "try before you buy".  This copy, although 
  61. unregistered, is fully functional.  Your support of GusDelay (by registering 
  62. it) will help ensure my continued support of GusDelay (by improving it).
  63.  
  64. This program, GUSDELAY.EXE, may be freely distributed provided that this 
  65. documentation accompanies the program, no fee is charged for the program
  66. (except for a NOMINAL media charge not to exceed US$5), and it is not 
  67. distributed as part of any commercial offering without prior written consent 
  68. of the author, David MacMahon.
  69.  
  70. TRADEMARKS - GusDelay is a trademark of David MacMahon.
  71.              Advanced Gravis, UltraSound, and USS 8 are trademarks 
  72.              of Advanced Gravis Computer Technology Limited.  
  73.              QEMM is a trademark of Quarterdeck Office Systems.
  74.              386MAX is a trademark of Qualitas Inc.
  75.  
  76.  
  77. ===============
  78. 1. INTRODUCTION
  79. ===============
  80. GusDelay is a program that transforms your Gravis UltraSound into an 
  81. extremely powerful yet easy to use digital delay system (DDS).  It has 
  82. features found only on professional DDSs that cost far more than the Gravis  
  83. UltraSound itself.
  84.  
  85. Features
  86. --------
  87. Here is a brief list of some of GusDelay's features:
  88.  
  89. *** Up to 14 individually controllable output taps - GusDelay can use this 
  90.     ability to create regenerative effects that are not degenerative.  
  91.     Single tap delay units must feed the output back into the input in order 
  92.     to create regenerative effects (such as multiple echoes or reverb).  
  93.     Each time the signal goes through the system it is degraded in quality.  
  94.     After several iterations the signal can be quite distorted.  With 
  95.     multiple taps, regenerative effects can be simulated without feeding the 
  96.     output back into the input thereby eliminating the degenerative side 
  97.     effects.
  98.  
  99. *** Sampling frequencies up to 44.1 kHz in both mono and stereo - GusDelay 
  100.     supports the entire sampling frequency range of the Gravis UltraSound.  
  101.         
  102. *** Jitter free and dropout free recording - GusDelay uses a technique for 
  103.     recording that produces higher quality recordings than other recording 
  104.     programs for the Gravis UltraSound including USS 8 and Playfile.
  105.  
  106. *** Real-time surround sound capabilities - GusDelay can produce real-time 
  107.     output that can be decoded by surround sound systems to produce true, 
  108.     on-the-fly surround sound effects.
  109.  
  110. *** Supports text based configuration files for plug-and-play usability 
  111.     and easy customization - GusDelay is highly configurable through the use 
  112.     of ASCII based configuration files.  This makes it easy for GusDelay 
  113.     users to save their favorite "presets" for quick recall, exchange their 
  114.     favorite settings with other users,  write simple programs to generate 
  115.     the settings for a mathematically calculated effect, and so on.
  116.  
  117. *** Command line arguments - GusDelay takes many of its parameters from the 
  118.     command line.  This enhances GusDelay's flexibility by allowing it to be 
  119.     started unattended from within batch files.
  120.  
  121. *** On-line help - GusDelay offers on-line help for the command line 
  122.     arguments as well as runtime operation.  This on-line quick reference 
  123.     information makes GusDelay easier to use.
  124.  
  125. Requirements
  126. ------------
  127. In order for GusDelay to work, there are two configuration requirements that 
  128. must be met.  The most important of which is that the UltraSound absolutely 
  129. MUST be set up to use two different DMA channels.  Due to the intensive 
  130. throughput of the program, the use of two different 16-bit DMA channels is 
  131. HIGHLY recommended.  The other requirement is that GusDelay must NOT be run 
  132. if a protected mode memory manager is loaded.  The protected mode memory 
  133. manager virtualizes the PC's hardware which slows down access to the DMA 
  134. controller.  This causes problems because GusDelay is very DMA intensive.  
  135. Future versions of GusDelay will coexist with these memory managers.  The 
  136. memory requirements for GusDelay are quite minimal so this should not cause 
  137. too much of a problem.  GusDelay should work on a computer with as little as 
  138. 512 KB of memory and with the standard GUS's 256 KB of on-board RAM.  
  139. Currently GusDelay does not take advantage of GUS memory beyond 256 KB.  
  140.  
  141. GusDelay checks for both of these requirements when it starts.  If either 
  142. one is not met GusDelay will print an appropriate message and exit.
  143.  
  144. Guide to the manual
  145. -------------------
  146. Here is a list of the remaining chapters of the manual.  A brief description 
  147. of each chapter is also given.
  148.  
  149. QUICK START INSTRUCTIONS - This chapter is for those who want to jump in 
  150. right away.  It describes the steps necessary to use some of GusDelay's 
  151. basic functionality.  It also explains how to use the on-line help.  It
  152. briefly mentions how to solve some of the problems that may be encountered.
  153.  
  154. COMMAND LINE REFERENCE - This chapter presents the various command line 
  155. arguments and how to use them.  Essentially, it is a more detailed version 
  156. of GusDelay's command line help.
  157.  
  158. RUNTIME COMMAND REFERENCE - This chapter covers the commands used to 
  159. interact with GusDelay during runtime.  It not only covers them in more 
  160. detail than GusDelay's runtime help, it also talks about the effects that 
  161. the various commands have on each other.  This chapter is very important for 
  162. anyone who will use GusDelay interactively (which includes almost everyone).
  163.  
  164. THEORY OF OPERATION - This chapter explains the technical details of 
  165. GusDelay.  Reading and understanding this chapter is not required in order 
  166. to use GusDelay, but those wishing to exploit the full power of GusDelay 
  167. should be familiar with the contents of this chapter.  Warning: This chapter 
  168. gets quite technical at times and may not be suitable for all viewers.
  169.  
  170. FILE FORMATS - This chapter outlines the file formats used by GusDelay. 
  171. These files are used to store user-definable look-up tables, user-definable 
  172. configurations (presets), and recorded data (sound).
  173.  
  174. FUTURE ENHANCEMENTS - This chapter lists features that could be added to 
  175. future versions of GusDelay.  These features show areas where GusDelay 
  176. could be enhanced.
  177.  
  178. CONTACTING THE AUTHOR - This appendix provides information about contacting 
  179. the author of GusDelay.
  180.  
  181. TROUBLESHOOTING - This appendix provides pointers for troubleshooting when 
  182. GusDelay does not operate as expected.  Look here if GusDelay doesn't seem 
  183. to be functioning properly.  If you have a "slower" system (by today's 
  184. standards) you may want to read this section first.
  185.  
  186. ===========================
  187. 2. QUICK START INSTRUCTIONS
  188. ===========================
  189. This chapter tells you how to get GusDelay up and running.  It introduces 
  190. you to some of GusDelay's basic functionality, including on-line help.  It 
  191. also touches upon some of GusDelay's more advanced features.  Along the way, 
  192. various problems that may be encountered are discussed and solutions to them
  193. are offered.
  194.  
  195. Starting GusDelay
  196. -----------------
  197. GusDelay can be started by simply typing "GusDelay" (no quotes) at the DOS 
  198. prompt when it is in the current directory.  This starts GusDelay using its 
  199. default values.  The defaults for GusDelay are to use line in, to sample at 
  200. 11025 Hz, and to operate in mono mode.  To start GusDelay with values other 
  201. than these, you must use command line arguments.  The chapter entitled
  202. "Command Line Reference" provides full details on all of the command line 
  203. arguments which GusDelay will accept.  The examples in this chapter assume 
  204. that GusDelay has been started with the default values.
  205.  
  206. Once GusDelay starts, you will see the following:
  207.    
  208.      GusDelay - Version 1.0
  209.      Copyright (c) 1994 by David MacMahon - All rights reserved.
  210.      Unregistered version for evaluation only.
  211.  
  212.      Press '?' for help.
  213.      Now using LUT pair 0.
  214.      Positive volume uses LUT 0 - Linear map, positive polarity
  215.      Negative volume uses LUT 1 - Linear map, negative polarity
  216.  
  217. The first three lines contain version, copyright, and registration 
  218. information.  The next three lines of text provide information regarding the 
  219. current look-up tables (LUTs) that are being used.  GusDelay uses two LUTs 
  220. at any given time, but it is possible to have more than one LUT pair in 
  221. memory.  For more information on LUTs, see the chapters entitled "Theory of 
  222. Operation" and "File Formats".
  223.  
  224. The other piece of information that is displayed is in the upper right hand 
  225. corner of the screen.  This is a four digit hexadecimal number that provides 
  226. information regarding the performance of the system.  The smaller this 
  227. number is, the better GusDelay is performing.  Note that this number will 
  228. never go below 0010 (for playback DMA channels less than 4) or 0020 (for 
  229. playback DMA channels greater than 4).  It is quite common for this number 
  230. to fluctuate slightly, but it should not vary widely.  When using high 
  231. sampling rates on slower systems, this number may grow rapidly until the 
  232. program spontaneously terminates.  This problem is much more likely to 
  233. happen in stereo mode.  If this occurs, it simply means that your system is 
  234. not able to provide the throughput necessary to maintain that sample rate.  
  235. The number displayed in the corner is actually the number of samples that 
  236. are currently being downloaded to the GUS.  This is referred to as the 
  237. "download size".  See the chapter entitled "Theory of Operation" for more 
  238. details.  For reference, my 25 MHz 386 system with a 32 KB cache running in 
  239. stereo with a sample rate of 44100 Hz has a download size that fluctuates 
  240. right around 00E0.  Another 25 MHz 386 system, without a cache, cannot keep 
  241. up at that rate.
  242.  
  243. Getting on-line help
  244. --------------------
  245. GusDelay has two forms of on-line help.  The first form is command line 
  246. help.  If you start GusDelay by typing "GusDelay -?", you will see a brief 
  247. summary of GusDelay's command line arguments.  The chapter entitled "Command 
  248. Line Reference" describes each argument in detail.  The second form of 
  249. on-line help is runtime help.  If you type a question mark while GusDelay is 
  250. running, you will see a brief summary of all of the valid commands that can 
  251. be used to control various aspects of GusDelay's operation.  The chapter 
  252. entitled "Runtime Command Reference" explains what each command does.
  253.  
  254. Creating an echo
  255. ----------------
  256. When GusDelay is started with the default values, none of the voices are 
  257. active.  In order to create any effect, you must first activate at least one 
  258. voice.  To activate a voice, press the '<Insert>' key.  The first inactive 
  259. voice will be activated with default values and you will see a line of text 
  260. similar to this:
  261.  
  262.      Voice  0: Pan = 15  Volume [0] = +0     Delay = 2756
  263.  
  264. This means that voice 0 is active, its pan position is 15 (all the way to 
  265. the right), its current volume is +0, and its delay is 2756.  The default 
  266. value of the delay is equal to one quarter of a second (250 mS).  See the 
  267. chapter entitled "Theory of Operation" for details about the minimum 
  268. allowable delay.  A voice has two volumes associated with it, a muted volume 
  269. (indicated by "[0]" following the word "Volume") and a normal volume 
  270. (indicated by "[1]" following the word "Volume").  When a voice is first 
  271. activated, its muted volume is its current volume.  By default, a voices 
  272. muted volume is 0 and its normal volume is 3600.  Pressing 'm' switches from 
  273. the muted volume to the normal volume and displays a line of text similar to 
  274. this:
  275.  
  276.      Voice  0: Pan = 15  Volume [1] = +3600  Delay = 2756
  277.  
  278. At this point you will hear (on the right channel) one echo of the input (on 
  279. the left channel).
  280.  
  281. Creating reverberation
  282. ----------------------
  283. Reverberation, more commonly referred to as reverb, is an effect created by 
  284. multiple echoes with very short delay times.  GusDelay can use two different 
  285. methods (or a combination of them) to create reverb.  The first method is 
  286. the same one used by conventional single tap delay units.  It creates 
  287. multiple echoes by mixing the output of the delay unit with the input to the 
  288. delay unit.  This method works, but it has three limitations.  The first 
  289. limitation is that if the feedback occurs in the analog domain (as with 
  290. GusDelay) then the signal degrades slightly every time it passes through 
  291. the system.  After a few iterations, it can become quite distorted.  The 
  292. second limitation to this system is that every echo has a delay time that is 
  293. an integral multiple of the shortest delay time.  The third drawback is that 
  294. the nature of the decay of the echoes is very regular; each echo's amplitude 
  295. is a certain percentage of the previous echo's amplitude.  Because of these   
  296. last two limitations, the regeneration method does not accurately model 
  297. real-world reverb and leads to an effect that can sound artificial.  The 
  298. second method of creating reverb uses multiple voices to generate multiple 
  299. echoes.  This method does not result in signal degradation because there is 
  300. no regeneration taking place in either the analog or the digital domain.  
  301. The multiple voice method allows each echo's delay time and amplitude to be 
  302. controlled independently from those of the other echoes.  These benefits 
  303. come at a slight cost of convenience.  Setting up multiple voices to 
  304. generate reverb is more involved than setting up one voice for regeneration.  
  305. The use of configuration files, however, means that this work only needs to 
  306. be done once.
  307.  
  308. To create multiple echoes using regeneration, move the pan position of a 
  309. voice towards the left.  Continuing the example started in the previous 
  310. section, change the pan position of Voice 0 from 15 to 7 by pressing '<' 8 
  311. times.  This will result in multiple echoes that decay away after several 
  312. iterations.  To increase the decay time of the echo, increase the voice's 
  313. volume by pressing 'Ctrl-<Up Arrow>' twice.  This will make the voice's 
  314. volume be +3800.  This will increase the number of echoes that can be heard 
  315. before they fade out.  Be careful, though, setting a voice's volume too high 
  316. will result in the echoes getting successively louder until all you have is 
  317. very loud noise.  Shortening the delay (by repeatedly pressing 'Ctrl-<Left 
  318. Arrow>') will create a reverb effect.  You must also be careful when doing 
  319. this.  GusDelay will let you shorten the delay to the "absolute minimum 
  320. delay" which is either 32 or 64 depending on the width of the playback DMA 
  321. channel.  This absolute minimum delay value is (usually) quite shorter than 
  322. the minimum delay that is actually realizable.  GusDelay calculates a "safe 
  323. minimum delay" value based on the throughput provided by your system at the 
  324. current sampling rate.  If you shorten the delay below this safe minimum 
  325. delay value, GusDelay will print an asterisk ('*') after the current delay 
  326. value.  The method by which GusDelay calculates the safe minimum delay 
  327. value is very conservative.  The actual safe minimum delay value is 
  328. somewhere between the calculated value and the absolute minimum delay value. 
  329. If you set the delay to be barely to short, the output will be choppy.  If 
  330. you set the delay extremely too short the output will, in effect, "wrap 
  331. around" and sound like an extremely long delay.
  332.  
  333. To create multiple echoes using multiple voices, you first need to activate 
  334. several voices and set their delays to different values.  Make sure that the 
  335. voices are panned all the way to the right (Pan = 15) or you will be using a 
  336. combination of the two methods.  Pressing '>' moves a voice's pan position 
  337. to the right.  Pressing '<Insert>' activates a new voice and makes it the 
  338. current voice.  The current voice is the voice that is affected by the 
  339. commands you type.  To select the current voice, press '<Page Up>' or 
  340. '<Page Down>'.  The current voice is always the last displayed voice on the 
  341. screen.  Pressing '<Space>' will display the settings of all active voices 
  342. and then display the settings of the current voice.  After you are done 
  343. using GusDelay, press '<Esc>', 'q', or 'Q' to exit.  There will be a slight 
  344. pause before GusDelay exits, especially at lower sample rates.  This is 
  345. normal.
  346.  
  347. Creating surround sound
  348. -----------------------
  349. Because GusDelay uses look-up tables (LUTs), it is able to implement a form 
  350. of "negative volume".  Negative volume is the same as positive volume except 
  351. that the output is the negated (or inverted).  Surround sound decoders 
  352. generate the back (or rear) channel by subtracting the left and right 
  353. channels (B = L - R).  They generate the front signal by adding the left and 
  354. right channels (F = L + R).  Surround sound is can be created by generating 
  355. the normal signal on the left channel, and the negated (or inverted) signal 
  356. on the right.  This results in the back channel being the same as adding the 
  357. left and right channels (B = L - (-R) = L + R).  Due to limitations in the 
  358. GUS's mixer prior to rev 3.7, surround sound in GusDelay is somewhat limited 
  359. in functionality.  It works best in stereo mode because signals going to 
  360. both channels will regenerate.  In mono mode, the signals going to the left 
  361. channel will regenerate, but signals going to the right channel will not.  
  362. You could compensate for this by setting up multiple voices on the right 
  363. channel and only one voice on the left channel (see the previous section 
  364. about creating reverberation).
  365.  
  366. The method for creating surround sound using stereo mode is given here.  
  367. First, start GusDelay in stereo mode ("GusDelay -s").  Activate a voice pair 
  368. by pressing '<Insert>'.  Switch the voices from their muted volume to their 
  369. normal volume by pressing 'm'.  At this point there is no surround sound 
  370. effect.  The echoes will be heard on the left, front, and right channels.  
  371. Press 'p' to change the relative polarities of the two voices.  At this 
  372. point you should hear the echoes alternating between the front and back 
  373. channels as well as being present on the left and right channels.  The 
  374. echoes alternate in this manner because the right channel inverts the echo 
  375. every time it passes through the system.  On even iterations, the polarity 
  376. of the echo on the right channel is the same as the polarity of the original 
  377. sound.  Even iteration echoes are heard on the front channel.  On odd 
  378. iterations, the polarity of the echo on the right channel is opposite the 
  379. polarity of the original sound.  Odd iteration echoes are heard on the back 
  380. channel.  Pressing 'p' cycles through all the possible relative polarities 
  381. of the two voices (i.e. +L +R, +L -R, -L -R, -L +R, and finally back to 
  382. +L +R).  Pressing 'P' cycles through in the opposite direction.  In mono 
  383. mode, pressing 'p' or 'P' simply toggles the polarity of the current voice.
  384.  
  385. Recording to disk
  386. -----------------
  387. GusDelay is able to record the input signal to disk, but not the output 
  388. signal.  If no regeneration is occurring, the recording will not contain any 
  389. echoes at all.  GusDelay saves the recorded data to disk in a raw, unsigned 
  390. format similar to the .SND files used by Playfile and USS 8.  There are 
  391. plenty of tools available to convert this file format into others.  To start 
  392. recording, press 'd'.  Once recording has begun, pressing 'd' pauses or 
  393. resumes recording.  The name of the output file defaults to "GUSDELAY.SND".  
  394. Using the "-o" switch on the command line can override this.  For example, 
  395. "GusDelay -o Terrapin.snd" would cause GusDelay to record to the file 
  396. "Terrapin.snd" (assuming that 'd' is pressed before quitting GusDelay).
  397.  
  398. When GusDelay records to disk, it greatly increases the bandwidth required 
  399. of the bus.  It is possible that at high sample rates the system may not be 
  400. able to keep up.  When this occurs, the number in the upper right corner 
  401. (the download size) will increase (rapidly) until the program spontaneously 
  402. terminates.  This simply means that your system is not able to provide the 
  403. throughput necessary for real-time delaying AND simultaneous recording to 
  404. disk at the sample rate you have selected.  If you wish to make recordings 
  405. at this high sample rate, you can use the "-d" switch on the command line.  
  406. This switch specifies that GusDelay is only going to be used for recording 
  407. to disk.  When operating in this "disk-only" mode, the delay functionality 
  408. of the program is unavailable.  For example, my 25 MHz 386 system is unable 
  409. to record in stereo with a sampling rate of 44100 Hz while it is 
  410. simultaneously providing delay functionality.  If I want to record at this 
  411. rate, I type "GusDelay -s -r 44100 -d" to start the program without the 
  412. delay functionality enabled.  This allows me to record at this rate.
  413.  
  414. GusDelay uses a unique (as far as I know) method of recording.  It is 
  415. capable of producing jitter free and dropout free recordings that are devoid 
  416. of "clicks".  At lower sampling rates, the difference in recording quality 
  417. between GusDelay and Playfile is not so noticeable, but at higher sampling 
  418. rates the difference is very noticeable.
  419.  
  420. =========================
  421. 3. COMMAND LINE REFERENCE
  422. =========================
  423. When GusDelay is started without any command line arguments, it uses default
  424. values for many of its operating parameters.  This chapter lists the 
  425. parameters which can be changed by specifying various arguments on the 
  426. command line.  GusDelay's default behavior and modified behavior is given 
  427. for each argument.  The text uses a dash ("-") as a prefix character for the 
  428. arguments.  GusDelay will accept either a dash or a forward slash ("/").  
  429. Multiple command line arguments can be given on the command line.  In 
  430. certain combinations, however, one or more of the given arguments may not 
  431. have any effect.
  432.  
  433. On-line help
  434. ------------
  435. On-line help regarding the command line arguments themselves can be obtained 
  436. by specifying "-h" or "-?" on the command line.  If either of these 
  437. arguments is given, GusDelay ignores any other arguments and displays a help 
  438. screen before returning to the DOS prompt.
  439.  
  440. Initial configuration file
  441. --------------------------
  442. Configuration files are used to store preset values for voice attributes 
  443. such as volume, pan position, and delay.  This makes it possible to quickly 
  444. setup GusDelay for preset effects.  Because the configuration files are 
  445. ASCII text files, it is easy to create your own and exchange them with other 
  446. GusDelay users via e-mail or other forms of communication.  GusDelay is also 
  447. capable of writing configuration files.  See the chapter entitled "Runtime 
  448. Reference" for more details.  To have GusDelay load a configuration file 
  449. during startup, add "-c <filename>" to the command line.  This will cause 
  450. GusDelay to use the settings specified in "<filename>" as the initial 
  451. configuration.  For example, "GusDelay -c carnegie.gd" will start GusDelay 
  452. using the settings specified in "carnegie.gd" (which may provide 
  453. reverberation similar to Carnegie Hall).  If the "-c" argument is not given, 
  454. GusDelay starts with the following voice attributes: 
  455.  
  456.      1) All voices deactivated.
  457.      2) All voices use muted volume when first activated.
  458.      3) The muted volume of all voices is 0.
  459.      4) The normal volume of all voices is 3600
  460.      5) The pan position of all voices in mono and the right (odd numbered) 
  461.         voices in stereo is 15.  Left (even numbered) voices in stereo have 
  462.         a default pan position of 0.
  463.      6) The delay of all voices is one quarter of a second (250 mS).
  464.  
  465. Disk-only mode
  466. --------------
  467. When using GusDelay to record to disk at high sample rates, it is possible 
  468. that slower systems may not be able to provide enough throughput to maintain 
  469. real-time delay AND the simultaneous writing to disk.  The "-d" argument 
  470. disables GusDelay's real-time delay feature.  When the delay feature is 
  471. disabled, GusDelay is in "disk-only mode".  In this mode, the only thing 
  472. that GusDelay can do is record to disk.  Obviously, GusDelay's default 
  473. behavior in the absence of this argument is to provide real-time delay.
  474.  
  475. Input selection
  476. ---------------
  477. GusDelay can sample the line level inputs, the microphone inputs, or both.  
  478. The default behavior is to sample the line level inputs.  To make GusDelay 
  479. sample the microphone inputs, add the "-m" argument to the command line.  If 
  480. just the "-m" argument is given, GusDelay disables the line level inputs.  
  481. To sample both the line level and microphone inputs, you must specify both 
  482. the "-m" and the "-l" arguments.  The "-l" switch enables the line level 
  483. inputs.  You can specify just the "-l" argument to enable only the line 
  484. level inputs.  Since this is the default behavior, however, it is redundant 
  485. and unnecessary.
  486.  
  487. Output file
  488. -----------
  489. When recording to disk, GusDelay will create a file called "GUSDELAY.SND".  
  490. If this file exists, it will be overwritten.  To record to an output file 
  491. other than "GUSDELAY.SND", add "-o <filename>" to the command line.  This 
  492. will make GusDelay record to an output file named "<filename>".  For 
  493. example, "GusDelay -o stairway.snd" will cause GusDelay to use 
  494. "stairway.snd" as the output file.
  495.    
  496. Sampling rate
  497. -------------
  498. GusDelay's default sampling rate is 11025 Hz.  To start GusDelay using a 
  499. different sampling rate, use the "-r <#>" argument.  This starts GusDelay 
  500. with a sampling frequency of <#> Hz.  For example,  "GusDelay -r 44100" 
  501. starts GusDelay with a sampling rate of 44100 Hz.  Because the GUS only 
  502. supports a limited number of distinct sampling rates, unsupported sampling 
  503. rates will be adjusted to one of the supported rates.  GusDelay will print a 
  504. message to this effect if it happens.  
  505.    
  506. Stereo mode
  507. -----------
  508. To use GusDelay in stereo mode, add the "-s" argument to the command line.  
  509. GusDelay's runs in mono mode by default.  Most people probably will prefer 
  510. to use mono mode most of the time.  This is because the mixer on Ultrasounds 
  511. prior to rev 3.7 had the not-so-wonderful "feature" of ALWAYS mixing the 
  512. input into the output and the output into the input.  Having things set up 
  513. this way results in the unavoidable regeneration of delayed signals, at 
  514. least in stereo.  In mono, things are a little bit better.  The GUS samples 
  515. only the left channel when sampling in mono.  By placing the output on the 
  516. right channel, the inadvertent feedback can not only be avoided, but 
  517. actually controlled.  As a voice gradually gets panned left, its 
  518. regeneration gradually increases.  This is actually quite desirable because 
  519. it means that the regeneration of each voice can be individually 
  520. controlled!  In mono mode this "feature" of the GUS is truly a feature.  In 
  521. stereo, however, this feature loses its appeal.  I have not had the 
  522. opportunity to test GusDelay on a GUS that has the modified mixer so I 
  523. don't know how it will perform.  My understanding is that the newer cards 
  524. can put the mixers in "transparent mode" which provides the same 
  525. functionality as the older GUSes.  Given this compatibility, GusDelay should 
  526. work the same on these newer cards.  Future versions of GusDelay will 
  527. support the "full mixer" found on newer cards.
  528.  
  529. Look-up table file
  530. ------------------
  531. GusDelay uses look-up tables (LUTs) to map a single input sample stream into 
  532. two output sample streams.  While only two LUTs are used at any given time, 
  533. it is possible to have more than two LUTs in memory.  Look-up tables, like 
  534. configurations, are stored in ASCII text files.  Unlike configuration files 
  535. which can contain only one configuration, LUT files can contain many 
  536. different LUTs.  To use GusDelay with a LUT file, add "-t <filename>" to the 
  537. command line.  This will cause GusDelay to use "<filename>" as a LUT file.  
  538. For example, "GusDelay -t metalfx.lut" will start GusDelay and load the LUTs 
  539. in "metalfx.lut" into memory.  If the -t argument is not present on the 
  540. command line, GusDelay uses its two internal LUTs.  Default LUT 0 maps 0 to 
  541. 0, 1 to 1, 2 to 2, etc.  This results in the output sample stream being the 
  542. same as the input sample stream.  Default LUT 1 maps 0 to 255, 1 to 254, 2 
  543. to 253, etc.  This results in an output stream that is the inverse of the 
  544. input stream.  This is a large part of how GusDelay implements "negative" 
  545. volume.
  546.  
  547. Extra wait factor
  548. -----------------
  549. GusDelay is designed to utilize as much bus bandwidth as possible.  The 
  550. "extra wait factor" argument can be used to force GusDelay to run with less
  551. than optimal efficiency.  This is primarily used in cases where GusDelay 
  552. does not react well at maximum efficiency with a particular system.  To use 
  553. an extra wait factor, add "-w <#>" to the command line, where <#> is a 
  554. number between 0 and 8.  The default value of the extra wait factor is 0.  
  555. See appendix 2, "Troubleshooting", for more details.
  556.  
  557. Examples
  558. --------
  559. This section lists a few possible combinations of command line switches and
  560. explains how they affects GusDelay's operation.
  561.  
  562.  Command Line:                            What it does:
  563.  
  564.  GusDelay -m -r 44100                     Starts GusDelay sampling the
  565.                                           microphone input in mono at a 
  566.                                           rate of 44100 Hz.
  567.  
  568.  GusDelay -c myroom.gd -t distort1.lut    Starts GusDelay sampling the line
  569.                                           level input in mono at a rate of 
  570.                                           11025 Hz.  The voices are 
  571.                                           initially configured as specified 
  572.                                           in the file "myroom.gd".  The 
  573.                                           look-up tables that will be used 
  574.                                           are stored in the file named
  575.                                           "distort1.lut".
  576.  
  577.  GusDelay -d -s -r 44100 -o quality.snd   Starts GusDelay in disk-only mode.
  578.                                           The line level inputs will be 
  579.                                           sampled in stereo at a rate of 
  580.                                           44100 Hz.  The output file will be 
  581.                                           named "quality.snd".
  582.  
  583. ============================
  584. 4. RUNTIME COMMAND REFERENCE
  585. ============================
  586. During the operation, or runtime, of GusDelay many aspects of the program 
  587. can be modified by issuing various keystroke commands.  This enables you to 
  588. dynamically "tweak" GusDelay until you get an effect you like.  At that 
  589. point, you can write the configuration to a file for future use.  If you get 
  590. a configuration file from someone and you feel that certain properties of 
  591. the configuration are not quite right for your GUS (e.g. too much or not 
  592. enough regeneration), you can use the commands described in this chapter to 
  593. manually trim the configuration to your liking.  This chapter covers all of 
  594. GusDelay's runtime commands.  For ease of learning, the commands are listed 
  595. in functional groups.
  596.  
  597. Many of the commands deal with voice manipulation.  In mono mode, all the 
  598. voices are used independently.  In stereo mode, however, voices are used in 
  599. pairs.  In mono mode, voice commands generally affect the current voice 
  600. only.  In stereo mode, voice commands generally affect both voices in the 
  601. current voice pair.  Throughout this chapter, the commands are primarily 
  602. described in the context of mono mode.  Unless otherwise noted, a command's  
  603. effect on the current voice in mono mode is similar to the command's effect 
  604. on the current voice pair in stereo.
  605.  
  606. On-line help
  607. ------------
  608. On-line help concerning the runtime operation of GusDelay can be obtained by 
  609. pressing '?' while the program is running.  This will clear the screen and 
  610. print a list of all the valid commands (keystrokes) and a brief explanation 
  611. of what each one does.  In disk-only mode, the list is much shorter than in 
  612. normal operation because many commands affect the delay portion of the 
  613. program.  These commands are unavailable in disk-only mode.
  614.  
  615. Activating, deactivating, and selecting voices
  616. ----------------------------------------------
  617. GusDelay uses up to 14 voices of the GF1 chip to create its output.  Voices
  618. that are in use are called "active voices".  Voices that are not in use are 
  619. called "inactive voices".  In stereo, voices are used in pairs so you can 
  620. have up to 7 pairs of active voices.  One of the active voices is considered 
  621. to be the "current voice".  The current voice is the voice whose parameters 
  622. will be changed when a voice altering command is given.  It is possible to 
  623. select which voice is the current one.  Here are the keystrokes to activate 
  624. voices, deactivate voices, and select the current voice from all active 
  625. voices.
  626.  
  627.       Insert - Activates the first inactive voice and makes it the current 
  628.                voice
  629.       Delete - Deactivates the last activated voice.  If this voice happens 
  630.                to be the current voice, then the next-to-last activated 
  631.                voice will become the new current voice
  632.      Page Up - Cycles the current voice through all active voices in 
  633.                ascending order
  634.    Page Down - Cycles the current voice through all active voices in 
  635.                descending order
  636.  
  637. Changing the volume of the current voice
  638. ----------------------------------------
  639. Voices in GusDelay have two volumes associated with them: a muted volume and 
  640. a normal volume.  Only one of a voice's two volume levels can be in effect 
  641. at any given time.  Both of these values can range from -4095 to +4095.  The 
  642. sign of the selected volume determines which of two output streams will be 
  643. used.  Positive volumes use the output stream associated with the even 
  644. numbered LUT in the current LUT pair.  Negative volumes use the output 
  645. stream associated with the odd numbered LUT of the current LUT pair.  The 
  646. absolute value of the selected volume is the actual volume used.  Note that 
  647. the volume scales are NOT linear.  If regeneration is occurring, setting the 
  648. volume too high can result in a positive feedback situation that will sound 
  649. like (surprise!) feedback.  Adjusting the volume to just below this 
  650. threshold creates some interesting effects.  Here are the keystrokes for 
  651. changing the volume of the current voice:
  652.           
  653.           Up Arrow - Increases the volume of the current voice by 10
  654.         Down Arrow - Decreases the volume of the current voice by 10
  655.      Ctrl Up Arrow - Increases the volume of the current voice by 100 
  656.    Ctrl Down Arrow - Decreases the volume of the current voice by 100 
  657.           'm', 'M' - Toggles between the current voice's muted and normal 
  658.                      volume
  659.            Alt-'M' - Sets every voice to its muted volume
  660.           'p', 'P' - In mono mode, toggles the polarity (sign) of the 
  661.                      current voice's volume
  662.    (lowercase) 'p' - In stereo mode, cycles through all the possible 
  663.                      combinations of volume polarity of the current voice 
  664.                      pair in the following order, +L/+R, +L/-R, -L-R, -L/+R
  665.    (uppercase) 'P' - In stereo mode, cycles through all the possible 
  666.                      combinations of volume polarity of the current voice 
  667.                      pair in the following order, +L/+R, -L/+R, -L-R, +L/-R
  668.    
  669. Changing the delay of the current voice
  670. ---------------------------------------
  671. The absolute minimum delay that a voice can have is 32 (for an 8-bit 
  672. playback DMA channel) or 64 (for a 16-bit playback DMA channel).  GusDelay  
  673. calculates a safe minimum delay by doubling the size of the largest playback 
  674. DMA transfer.  This value is typically larger than the realizable minimum 
  675. delay value.  The maximum delay a voice can have is equal to the size of 
  676. one GUS memory buffer minus the absolute minimum delay.  The size of the 
  677. GUS memory buffer is approximately equal to (256K / n), where n is 2 for 
  678. mono mode or 4 for stereo mode.  
  679.  
  680. Theoretically, two voices with opposite volumes but the same delay value and 
  681. pan position should exactly cancel each other.  In GusDelay, however, the 
  682. procedure for setting a voice's delay to a particular value is not very 
  683. precise.  If two such voices are independently set to the same delay, it is 
  684. unlikely that the two voices will exactly cancel each other.  To circumvent 
  685. this, GusDelay is able to set the delay of two voices simultaneously.  This 
  686. way, even if the voices are not set to the exact delay requested, both 
  687. voices will be off by the same amount and will exactly cancel each other 
  688. (assuming they have the same pan position and opposite volume).  This is 
  689. referred to as "binding" the voices' delays.  When binding delays, one voice 
  690. is the "master" and the other voice is the "slave".  When a master's and 
  691. slave's delays are bound, the delays of both voices are set to the delay of 
  692. the master voice.  Only certain master/slave combinations are allowed.  In 
  693. mono mode, even numbered voices are bound to the next higher voice, 
  694. regardless of which one is the master.  In stereo mode, even numbered voice 
  695. pairs (voice pairs whose left voice is divisible by 4) are bound to the next 
  696. higher voice pair regardless of which pair is the master.  Because GusDelay 
  697. only supports 14 voices, voice pair (12, 13) can not be bound.  The current 
  698. voice (or, in stereo, voice pair) is the master voice.  For example, in mono 
  699. mode, if voice 5 is the current voice and 'b' (the "bind voice delays" 
  700. command) is pressed, the delays of voice 4 and voice 5 will be set to the 
  701. current delay of voice 5.
  702.  
  703. Here are the keystrokes for changing the delay of the current voice and, in 
  704. the case of the "bind voice delays" command, the delay of its corresponding 
  705. slave voice.
  706.      
  707.                 '+' - Increases the delay of the current voice by 10
  708.                 '-' - Decreases the delay of the current voice by 10
  709.                 '*' - Increases the delay of the current voice by 100
  710.                 '/' - Decreases the delay of the current voice by 100
  711.         Right Arrow - Increases the delay of the current voice by 50
  712.          Left Arrow - Decreases the delay of the current voice by 50
  713.    Ctrl Right Arrow - Increases the delay of the current voice by 500
  714.     Ctrl Left Arrow - Decreases the delay of the current voice by 500
  715.             '0'-'9' - Sets the last digit of the current voice's delay
  716.            'b', 'B' - Bind voice delays (see above)
  717.  
  718. Note: If the delay of a voice is adjusted to below the safe minimum delay 
  719. then an asterisk ('*') will be printed after the voice's current delay.
  720.  
  721. Changing the pan position (balance) of the current voice
  722. --------------------------------------------------------
  723. The pan position of a voice can range from 0 (all the way to the left) to 15 
  724. (all the way to the right).  In mono mode, voices start with a pan position 
  725. of 15 by default.  See the "Stereo mode" section of the "Command Line 
  726. Reference" chapter for the reason behind this.  In stereo mode, voice pairs, 
  727. by default, start with the even numbered (left) voice at pan position 0 and 
  728. the odd numbered (right) voice at pan position 15.  Changing the pan 
  729. position of the current (stereo) voice pair will affect the separation.  
  730. After 7 changes away from the initial pan positions, both voices will be 
  731. just about dead center (no separation).  After 15 changes away from the 
  732. initial pan positions, the left voice will be all the way to the right and 
  733. the right voice will be all the way to the left.
  734.  
  735.    '>' - Increases the value of the pan position of the current voice by 1.
  736.          In stereo, this increases (by 1) the pan position of the left voice
  737.          of the current voice pair and decreases (by 1) the pan position of
  738.          the right voice.  This has the effect of decreasing the separation
  739.          (unless the voices have "crossed", in which case the separation is
  740.          increased.)  In mono, this decreases the regeneration of the current
  741.          voice.
  742.    '<' - Decreases the value of the pan position of the current voice by 1.
  743.          In stereo, this decreases (by 1) the pan position of the left voice
  744.          of the current voice pair and increases (by 1) the pan position of
  745.          the right voice.  This has the effect of increasing the separation
  746.          (unless the voices have "crossed", in which case the separation is
  747.          decreased.)  In mono, this increases the regeneration of the current
  748.          voice.
  749.  
  750. Displaying voice information
  751. ----------------------------
  752. Information about the parameters of all active voices can be obtained at any 
  753. time by pressing the space bar.  This will list all the active voices and 
  754. their parameters.  The information about the current voice is printed on a 
  755. line following this list.
  756.    
  757. Configuration files
  758. -------------------
  759. GusDelay can read and write configuration files on the fly.  This allows you 
  760. to quickly change from one effect to another.  It also allows you to save 
  761. newly created effects to disk for later use.  Whenever a configuration file 
  762. command is given (read or write), GusDelay prompts you for the file name to 
  763. use.  Here are the keys used to read and write configuration files from 
  764. within GusDelay:
  765.  
  766.    (lowercase) 'c' - Read configuration to file (after prompting for name)
  767.    (uppercase) 'C' - Write configuration to file (after prompting for name)
  768.  
  769. Look-up tables
  770. --------------
  771. As mentioned in the "Look-up table file" section of the "Command Line 
  772. Reference" chapter, GusDelay only uses two look-up tables (LUTs) at any 
  773. given time.  There can be more than one pair of LUTs in memory, but only one 
  774. pair can be used at any time.  Pressing 'l' (or 'L') causes the next LUT 
  775. pair to be used.  If the last LUT pair is in use, pressing 'l' selects the 
  776. first LUT pair.
  777.    
  778. Recording to disk
  779. -----------------
  780. When GusDelay first starts, recording to disk is off.  Pressing 'd' (or 'D') 
  781. will start recording to disk.  From that point on, the 'd' (or 'D') key acts 
  782. as a pause/resume button, toggling the recording off and on.  Note that 
  783. GusDelay can only record the inputs of the GUS.  It can not directly record 
  784. the outputs.  GusDelay will record the data in a file called "GUSDELAY.SND" 
  785. unless "-o <filename>" was given on the command line.  In that case, the 
  786. data will be recorded in a file named "<filename>". If the program 
  787. unexpectedly terminates while recording to disk, see the "Disk-only mode" 
  788. section of the "Command Line Reference" chapter.
  789.    
  790. Quitting GusDelay
  791. -----------------
  792. To quit GusDelay, press '<Esc>', 'q', or 'Q'.  There will be a slight pause 
  793. before GusDelay actually terminates.  If you are using a low sampling rate, 
  794. this pause will be somewhat longer.
  795.  
  796. ======================
  797. 5. THEORY OF OPERATION
  798. ======================
  799. GusDelay takes advantage of the fact that the Gravis UltraSound is able to 
  800. use two separate DMA channels for recording and playback.  Because of this, 
  801. it makes heavy use of memory buffers.  To a great degree, GusDelay also 
  802. relies on the architecture of the UltraSound itself.  For these reasons it 
  803. makes sense to talk about GusDelay in two different contexts.  The first 
  804. context is data flow.  The term "data flow" refers to the movement of data 
  805. along the path from input to output.  The second context is signal flow.  
  806. The term "signal flow" refers to the movement of signals along the path from 
  807. input to output.  Although these two terms seem superficially synonymous, 
  808. they are in fact quite different.  The data flow context is physical in 
  809. nature.  Signal flow is more of an abstract or logical context.  One can 
  810. think of signal flow as *what* the program actually does while data flow can 
  811. be thought of as *how* the program actually does it.
  812.  
  813. Data Flow - Buffers, Buffers, and Buffers
  814. -----------------------------------------
  815. During the execution of GusDelay, data is constantly moving from the input 
  816. to the output through various stages of processing.  The input of data 
  817. occurs at a constant rate that is directly dependent on the sampling 
  818. frequency.  Because the CPU can not be dedicated solely to the handling of 
  819. these data, each stage of processing has an associated set of buffers to 
  820. collect the data until the CPU is ready to process that stage.  Here is a 
  821. block diagram of the buffer sets used in GusDelay:
  822.  
  823.                +-----+    +----------+    +-----+   
  824.                |     |    | Record   |    |     |    +--------+
  825. Analog In  ~~~>|     |===>| Buffers  |--->|     |    |  Disk  |
  826.                | GUS |    +----------+    | CPU |--->| Buffer |-=-> To Disk
  827. Analog Out <~~~|     |<===| Download |<---|     |    +--------+
  828.                |     |    | Buffers  |    |     |
  829.                +-----+    +----------+    +-----+
  830.  
  831. ~~~> denotes an analog data path
  832. ===> denotes a DMA based digital data path
  833. ---> denotes a non-DMA based digital data path
  834. -=-> denotes a digital data path that may or may not be DMA based
  835.  
  836.                                  Figure 1.
  837.  
  838. This diagram shows that data move from the GUS to the record buffers via 
  839. DMA.  The CPU is responsible for transferring this data from the record 
  840. buffers to the download and disk buffers in a timely fashion.  Data in the 
  841. download buffers are moved, via DMA, to more buffers (not shown) on the GUS.  
  842. Data in the disk buffer are written to disk.  In addition to what is 
  843. depicted, the CPU is in charge of initiating the DMA transfers, handling the 
  844. writing of data to disk, taking care of the user interface, and maintaining 
  845. DOS (i.e. handling interrupts).  It is clear from this diagram that the CPU 
  846. moves data from buffer to buffer, but the actual timing and implementation 
  847. of these movements are not shown.
  848.  
  849. The two data movements performed by the CPU are record buffer to disk buffer 
  850. and record buffer to download buffer.  The movement of data from the record 
  851. buffer to the disk buffer is simply a copy.  The movement of data from the 
  852. record buffer to the download buffer is more complex.  There is some 
  853. processing done on the data as they are copied from the record buffer to the 
  854. download buffer.  This processing involves using the input samples as 
  855. indexes into a look-up table.  The entries in the look-up table are used as 
  856. output samples.  In stereo mode there is a little more processing because 
  857. the input samples are interleaved, but the output samples are not.
  858.  
  859. The timing of these data movements is interrupt driven.  After some samples 
  860. have been transferred to the record buffers, the data movement routine is 
  861. invoked.  This routine does the following things:
  862.         
  863.         1. Copies the new samples to the disk buffer
  864.         2. Processes the new input samples, placing the resulting 
  865.            output samples into the download buffers.
  866.         3. Starts the download of the first download buffer
  867.  
  868. The completion of the download triggers an interrupt.  The interrupt handler 
  869. function calls a routine in GusDelay that starts the download of the next 
  870. download buffer.  If all download buffers have been downloaded and there are 
  871. enough new samples to start another round of downloads, the data movement 
  872. routine is called.  If there are not enough new samples at this time, one of 
  873. the GUS's timers is started to trigger an interrupt when there will be 
  874. enough new samples for another round of downloads.  The number of bytes in a 
  875. download is called the "download size".  Due to the dynamic nature of the 
  876. timing of these routines, not all download sizes are equal.
  877.  
  878. This data-movement-and-download process is repeated until the program 
  879. terminates.  The time it takes for a new sample to propagate from the GUS's 
  880. ADC to the GUS's RAM determines the actual minimum delay that can be 
  881. realized.  This time is dependent on the download size (i.e. the larger the 
  882. download size, the longer samples have been in the PC's memory).  
  883. Theoretically, the minimum realizable delay is approximately equal to twice 
  884. the time represented by the download size.  In practice, however, the 
  885. minimum realizable delay is somewhat higher than this.  I don't know if 
  886. this is due to a problem in the theory or the implementation, but future 
  887. versions of GusDelay will address this issue.  GusDelay keeps track of the 
  888. largest download size and sets the safe minimum delay equal to twice this 
  889. value.  This is a very conservative approach, but this value is intended to 
  890. be only a guideline.
  891.  
  892. Signal Flow - Channels, Tracks, and Voices
  893. ------------------------------------------
  894. Now that the flow of data through the system is understood, the flow of 
  895. signals through the system can be discussed.  Throughout this section the 
  896. terms channel, track, and voice are used with specific meaning.  Because the 
  897. meanings used in this text differ slightly from their conventional meanings, 
  898. their definitions are given here.
  899.  
  900. Channel - A channel refers to a single audio signal.  Anything that is 
  901.           mono has only one channel.  Anything that is stereo has two 
  902.           channels.  A channel signal can exist in digital or analog form 
  903.           (or both).
  904.  
  905. Track -   A track is similar to a channel in that it refers to a single 
  906.           audio signal, but a track signal differs from a channel signal 
  907.           because a track signal can only exist in digital form.  Channel 
  908.           signals are mapped into track signals.  A single channel can have 
  909.           more than one mapping and, therefore, more than one associated 
  910.           track.  GusDelay uses two tracks per channel.
  911.  
  912. Voice -   A voice is logical element of the GF1 chip that plays a track 
  913.           signal and directs it to the output channels.  GusDelay supports 
  914.           up to 14 voices.
  915.  
  916. Understanding the relationships between channels, tracks, and voices is a 
  917. prerequisite for understanding the flow of signals in GusDelay.  The 
  918. following diagram illustrates the signal flow of GusDelay operating in
  919. stereo mode.  Mono mode is similar in operation, but has only one channel 
  920. and two tracks.
  921.                                                              Download
  922.                                                              Buffers
  923.                                                            +---------+   
  924.                                                      /---->| Track 0 |=====\
  925. Audio                                                |     +---------+     |
  926.  In       +-------+        +-----+    +---------+    |/--->| Track 1 |====\|
  927. ~~~~~+~~~>| Mixer |~~~~~~~>| ADC |===>| Record  |----+     +---------+     |
  928.      |    +-------+        +-----+    | Buffers |    |\--->| Track 2 |====\|
  929.      |       /|\                      +---------+    |     +---------+     |
  930.      |        |                                      \---->| Track 3 |====\|
  931.      |        +~~~~~~~~+                                   +---------+     |
  932.      |                 |                                                   |
  933.      +~~~~~~~~+        |                                   +---------+     | 
  934.               |        |                             /-----| Track 0 |<===/|
  935.              \|/       |              +---------+    |     +---------+     |
  936.           +-------+    |   +-----+    |         |    |/----| Track 1 |<===/|
  937. <~~~~~~~~~| Mixer |<~~~+~~~| DAC |<---|   GF1   |<---+     +---------+     |
  938. Audio     +-------+        +-----+    |         |    |\----| Track 2 |<===/|
  939.  Out                                  +---------+    |     +---------+     |
  940.                                                      \-----| Track 3 |<====/
  941. ~~~> denotes an analog stereo signal path                  +---------+
  942. ===> denotes a DMA based digital signal path                   GUS
  943. ---> denotes a non-DMA based digital signal path             Buffers
  944.  
  945.                                  Figure 2.
  946.  
  947. The output of the ADC is transferred via DMA to the record buffers.  These 
  948. data consist of interleaved samples of two audio channels (left and right). 
  949. Using the mechanism described in the preceding section, the interleaved 
  950. samples of these two channel signals are processed using two different 
  951. mappings (look-up tables) to produce four track signals.  The samples of the 
  952. four track signals are placed in the download buffers.  The relationship 
  953. between the channel signals and the track signals is summarized in this 
  954. table:
  955.  
  956.                        Track    Channel   Mapping
  957.                        --------------------------
  958.                          0         L         0
  959.                          1         R         0
  960.                          2         L         1
  961.                          3         R         1
  962.  
  963.                                 Table 1.
  964.  
  965. After the samples of the track signals are in the download buffers they are 
  966. downloaded to the corresponding buffers in the GUS's RAM.  These GUS buffers 
  967. are much larger than the download buffers.  Once the track signals are in 
  968. the GUS's RAM, voices of the GF1 chip can be used to transform these track 
  969. signals back into channel signals. 
  970.  
  971. In order to use a voice for playing the track signals into channel signals,
  972. the voice's number, volume, pan position, and delay must be specified.  
  973. Since a voice can play samples from only one track at a time, the track used 
  974. by a voice must also be known.
  975.  
  976. GusDelay determines the voice's track based on the the voice's volume and, 
  977. in stereo, the voice's number itself.  The GF1 allows a voice's volume to be 
  978. any value between 0 and 4095, inclusive.  GusDelay allows a voice's volume 
  979. to be any value between -4095 and 4095.  The sign of a voice's volume 
  980. determines which mapping it will use and the absolute value of its volume is 
  981. the actual volume that is given to the GF1.  Voices with positive volume use 
  982. mapping 0, voices with negative volume use mapping 1.  Using the sign of the 
  983. voice's volume to determine the mapping allows GusDelay to actually simulate 
  984. negative gain (inversion) provided that the mapping is set up properly.  
  985. GusDelay's default mapping provides this functionality.  In mono mode, 
  986. mapping 0 implies track 0 and mapping 1 implies track 1.  In stereo mode, 
  987. however, an additional piece of information is needed to determine which 
  988. track will be used by a voice.  GusDelay uses the LSB of the voice's number 
  989. to determine which input channel to use.  Even numbered voices use the left 
  990. input channel and odd numbered voices use the right input channel.  For 
  991. example, voice 2 with a volume of 3400 will use track 0 while voice 5 with a 
  992. volume of -3500 will use track 3.  
  993.  
  994. The output channels of a voice are determined by the voice's pan position.
  995. The output of each voice can be panned to any one of 16 pan positions 
  996. ranging from full left to full right.  This allows one voice to output on 
  997. either or both channels.   The input channel used by a voice is not 
  998. necessarily the same as the output channel.  It is possible for a voice to 
  999. play the left input channel mostly on the right output channel and vice 
  1000. versa.  Due to the limited nature of the mixer on the GUS prior to rev 3.7, 
  1001. there is no way, in stereo mode, to prevent the output from mixing back into 
  1002. the input (unless you have bypassed the GUS's mixer altogether). This means 
  1003. that, in stereo mode, the output of a voice always regenerates. In mono 
  1004. mode, since the GUS samples the left channel only, adjusting the voice's pan 
  1005. position all the way to the right prevents any feedback to the input stages.
  1006. By varying a voice's pan position, it's regeneration can be controlled.  
  1007. With rev 3.7 (and later) of the GUS, this problem/feature does not exist, 
  1008. but this version of GusDelay is not written to take advantage of the new 
  1009. features of the newer cards.
  1010.  
  1011. The location of the voice in the track signal GUS buffer is determined by 
  1012. the voice's delay value.  The delay value of a voice is the number of 
  1013. samples by which the voice lags the present.  The delay value can be used to 
  1014. calculate the voice's offset within the GUS buffer.  When the delay value of 
  1015. a voice is changed, the voice's position must be changed to reflect the new 
  1016. delay.  The method by which GusDelay does this is not very precise.  If two 
  1017. voices are set up with the same delay, it is unlikely that they will 
  1018. actually be positioned at the same offset within their respective track 
  1019. buffers.  For this reason, the concept of "voice binding" was added to 
  1020. GusDelay.  Voice binding takes one voice's delay and forces that voice and a 
  1021. second voice to be positioned at exactly the same offset based on the delay 
  1022. of the first voice.  If the default mappings are in effect, binding two 
  1023. voices with the same pan position, same delay, and opposite volumes will 
  1024. cause them to exactly cancel each other.
  1025.  
  1026. A thorough understanding of the concepts that were presented in this chapter 
  1027. is not required to use GusDelay.  Knowing how GusDelay works, however, makes 
  1028. it easier to create custom look up tables (LUTs) and configuration (presets) 
  1029. files.  The ability to customize these aspects of GusDelay greatly enhances 
  1030. its versatility and usefulness.
  1031.  
  1032. ===============
  1033. 6. FILE FORMATS
  1034. ===============
  1035. GusDelay uses three different file types: look-up table (LUT) files, 
  1036. configuration files, and sound files.  This chapter explains the formats of 
  1037. these file types.  LUT files and configuration files are ASCII text files 
  1038. that allow the user to customize GusDelay.  Sound files are binary files 
  1039. that contain data recorded by GusDelay.  GusDelay comes with a sample LUT 
  1040. file and a sample configuration file.  They are both usable, but they are 
  1041. intended to be more instructional than useful.
  1042.  
  1043. LUT files and configuration files have some similarities beyond the fact 
  1044. that they are both ASCII text files.  They are both composed of "tokens".  
  1045. Tokens are groups of non-white space characters delimited by white space 
  1046. characters.  This means that these files are not very sensitive to line 
  1047. spacing and can be quite free-form.  Both file types also have the same 
  1048. "comment characters".  Comment characters cause all remaining characters on 
  1049. that line to be ignored.  There are three comment characters: ';' 
  1050. (semicolon), '#'(number sign), and '"' (double quote).  The ';' and '#' 
  1051. characters are comment characters in the traditional sense.  Everything 
  1052. after them is ignored (until the end of the line).  The '"' character is a 
  1053. little different.  Characters after it (until the end of the line) are not 
  1054. parsed as tokens, but they are echoed to the screen.  This is useful for 
  1055. embedding such things as the file creator's name, reminder messages to the 
  1056. user, etc.  
  1057.  
  1058. Look-up table (LUT) files
  1059. -------------------------
  1060. The first three tokens of a LUT file are all integers.  They indicate the 
  1061. number of LUTs that GusDelay should create in memory, the number of entries 
  1062. per LUT, and the number of bytes per entry.  Currently, the number of 
  1063. entries per LUT and the number of bytes per entry MUST be set to 256 and 1,
  1064. respectively.  After parsing these three tokens, GusDelay will create as 
  1065. many LUTs as specified by the first token.  These LUTs are initially set up 
  1066. to be identical to the default LUTs.  Even numbered LUTs, by default, have a 
  1067. 1:1 mapping (i.e. 0 maps to 0, 1 maps to 1, 2 maps to 2, etc.).  Odd 
  1068. numbered LUTs, by default, have a 1:-1 mapping (i.e. 0 maps to 255, 1 maps 
  1069. to 254, 2 maps to 253, etc.).  The remainder of the LUT file is composed of 
  1070. LUT entry records or LUT name records.
  1071.  
  1072. A LUT entry record consists of three tokens, all integers.  The first token 
  1073. in a LUT entry record is the number of the LUT which this entry modifies.  
  1074. The second token is the number of the LUT entry to modify.  The third token 
  1075. is the new value for this entry.  LUT entry records are only required for LUT entries that 
  1076. differ from the default entries.  For example, the tokens "2 37 53 3 214 98" 
  1077. would cause GusDelay to set entry 37 of LUT 2 to 53 and entry 214 of LUT 3 
  1078. to 98.
  1079.  
  1080. A LUT name record consists of two or more tokens.  The first token in a LUT 
  1081. name record is the number of the LUT that is being named.  The first 
  1082. character of the second token is non-numeric.  This fact is important 
  1083. because it is how GusDelay differentiates between a LUT entry record and a 
  1084. LUT name record.  The second token and the remainder of the text on that 
  1085. line of the LUT file make up the name of the LUT specified by the first 
  1086. token.  For example, if "2 37 53 2 Random mapping" appeared as one complete 
  1087. line of a LUT file, GusDelay would set entry 37 of LUT 2 to 53 and would set 
  1088. the name of LUT 2 to "Random mapping".  The name of a LUT is displayed when 
  1089. the LUT is activated.
  1090.  
  1091. GusDelay comes with a sample LUT file called GUSDELAY.LUT.  This file 
  1092. specifies 4 LUTs, but only modifies LUTs 2 and 3.  This means that LUTs 0 
  1093. and 1 will contain only the default values.  Also note that GUSDELAY.LUT 
  1094. only modifies half of the entries in LUTs 2 and 3.  LUT 2 is a positive 
  1095. rectifier.  This causes all negative input voltages to become positive
  1096. output voltages (ignoring the fact that the output is AC coupled).  It 
  1097. should be noted that the look-ups map unsigned values into unsigned values.  
  1098. As it turns out, 0 produces the highest (most positive) output voltage and 
  1099. 255 produces the lowest (most negative) output voltage.  
  1100.    
  1101. Configuration files
  1102. -------------------
  1103. Configuration files are composed of voice selection records and voice 
  1104. attribute records.  Both types of records contain two tokens.  Voice 
  1105. selection records are used to select which voice's attributes will be 
  1106. affected by subsequent voice attribute records.  Voice attribute records 
  1107. affect various attributes of the voice selected by the most recent voice 
  1108. selection record.  
  1109.  
  1110. The first token of a voice selection record is a single character token, 
  1111. either a "v" or a "V".  The following token, an integer, specifies the 
  1112. number of the voice that will be affected by subsequent voice attribute 
  1113. records.  When a new voice selection record is encountered, the previously 
  1114. selected voice will not be further affected unless it is selected again with 
  1115. another voice selection record.  Voice selection records also imply that the 
  1116. selected voice (and all other voices with smaller voice numbers) will be an 
  1117. active voice after the configuration file is processed.
  1118.  
  1119. The structure of a voice attribute record is virtually identical to the 
  1120. structure of a voice selection record.  The first token is a single 
  1121. character specifying which attribute of the currently selected voice will be 
  1122. given a new value.  The second token, an integer, is the value given to that 
  1123. attribute.  There are four attributes of a voice that can be changed: muted 
  1124. volume, normal volume, delay, and pan position.  There are, however, six 
  1125. different types of voice attribute records which are summarized in the 
  1126. following table:
  1127.  
  1128.         First token     Meaning of the value of the second token
  1129.         -----------     ----------------------------------------
  1130.                 'm'     Sets the muted volume of the current voice
  1131.                 'M'     Sets the muted volume of the current voice AND 
  1132.                         specifies that the current voice will use this
  1133.                         volume after the configuration file is processed.
  1134.                 'n'     Sets the normal volume of the current voice
  1135.                 'N'     Sets the normal volume of the current voice AND 
  1136.                         specifies that the current voice will use this
  1137.                         volume after the configuration file is processed.
  1138.          'd' or 'D'     Sets the delay (in samples) of the current voice.
  1139.          'p' or 'P'     Sets the pan position of the current voice.
  1140.  
  1141. Unless 'N' is explicitly used for a voice (and not followed by an 'M'), its 
  1142. volume after the configuration file is processed will be its normal volume.
  1143.  
  1144. Currently, GusDelay configuration files do not specify global options such 
  1145. as sampling rate, stereo or mono mode, etc.  For any given configuration 
  1146. file, appropriate values for these options must be given on the command line 
  1147. or the effect obtained will not be the one intended.  Future versions of 
  1148. GusDelay will address this issue.  If certain attributes of a voice are not 
  1149. specified in the configuration file, those attributes will take on their 
  1150. default values.  These default values were listed in the "Initial 
  1151. configuration file" section of the chapter entitled "Command Line 
  1152. Reference".
  1153.  
  1154. GusDelay comes with a sample configuration file, GUSDELAY.CFG, that uses 
  1155. three voices to create reverb/echo.  Two of the voices are configured for no  
  1156. regeneration while the third voice is set to regenerate.  This produces a 
  1157. rather pleasing effect.  It should be noted that by having only one voice 
  1158. regenerate, the reverb "pattern" is effectively regenerated as a whole.  In 
  1159. other words, even though voices 0 and 1 don't regenerate, they will still 
  1160. provide one and only one echo for each and every regeneration of voice 2.
  1161.  
  1162. Sound files
  1163. -----------
  1164. The sound files created by GusDelay are simply raw samples.  These samples 
  1165. are 8-bit unsigned integers.  Stereo sound files interleave the samples of 
  1166. left and right channels.  For any corresponding pair of samples, the left 
  1167. channel's sample comes first.  This is the same format used by the .SND 
  1168. files of Playfile and USS 8.  There are a number of utilities that can be 
  1169. used to convert this file format into other formats.  GusDelay can create 
  1170. stereo recordings at any of the sample rates supported by the GUS.
  1171.  
  1172. ======================
  1173. 7. FUTURE ENHANCEMENTS
  1174. ======================
  1175. Even though the current version of GusDelay has quite a bit of 
  1176. functionality, there are more features I would like to add.  Some of these 
  1177. offer new functionality while others offer increased ease of use.  The next 
  1178. release of GusDelay will most likely be 1.1.  It will offer an enhanced 
  1179. feature set (i.e. bug fixes) as well as some additional functionality.  I 
  1180. can't list what bugs will be fixed because as far as I know, there are no 
  1181. bugs, only misunderstood "features".  I am relying on you to tell me which 
  1182. "features" need to be better behaved.  Likewise, I can't list what 
  1183. functionality will be added.  It depends on how urgently "features" need to 
  1184. be improved.  As with any software project, improving existing features and 
  1185. adding new functionality need to be carefully balanced.  Registered users 
  1186. will have a great deal of influence on the future of GusDelay (and will be 
  1187. automatically registered for all future versions).  That said, here is a 
  1188. list of functionality that I would like to eventually incorporate into 
  1189. GusDelay:
  1190.  
  1191.  - Graphical user interface (probably TurboVision)
  1192.  - Create .WAV (and other formats) files instead of just raw data files
  1193.  - Support for more than 256K of GUS DRAM
  1194.  - Flanger effect - This will fluctuate a voice's playback frequency above
  1195.    and below the recording frequency
  1196.  - Chorus effect - This will fluctuate a voice pair's volume.
  1197.  - Adjustable maximum delay
  1198.  - Ability to change loop mode - Allow voices to loop bidirectionally.  
  1199.    This, in combination with the adjustable maximum delay, can create some 
  1200.    bizarre effects
  1201.  - More flexible configuration files
  1202.  - Better coexistence with protected mode memory managers
  1203.  - Support for the improved mixers on newer GUSes
  1204.  - Support for the 16-bit daughter card and GUS MAX
  1205.  - Make GusDelay MIDI aware.  There must be MIDI-aware delay modules and 
  1206.    there is no reason that GusDelay could not offer this functionality.
  1207.  - Other enhancements mentioned in the text
  1208.  - Your excellent idea here - I am always willing to consider new ideas
  1209.  
  1210. The flanger and chorus effects are my personal favorites.
  1211.  
  1212. =========================
  1213. A1. CONTACTING THE AUTHOR
  1214. =========================
  1215. I can be reached via e-mail at davidm@marcam.com.  I am very interested in
  1216. your feedback, both good and bad, and will try to respond to all of it.  I
  1217. also read the "GUS SDK Digest", the "Ultrasound Daily Digest", the "GUS 
  1218. Musicians' Digest", and the USENET news group comp.sys.ibm.pc.soundcard.
  1219.  
  1220. ===================
  1221. A2. TROUBLESHOOTING
  1222. ===================
  1223. I have put much effort into ensuring that GusDelay will run well on as many 
  1224. different computers in as many different configurations as possible.  This 
  1225. does not mean that it will run well on every computer.  The two biggest 
  1226. causes of problems that I have seen are running GusDelay with a protected 
  1227. mode memory manager and running GusDelay on "slower" computers.  Here is a 
  1228. list of symptoms and likely solutions for them.
  1229.  
  1230. SYMPTOM 1: GusDelay complains that my DMA channels are the same.
  1231.  
  1232. SOLUTION 1: GusDelay requires that the UltraSound be configured to use two 
  1233. different DMA channels.  Consult the documentation that came with the 
  1234. UltraSound for instructions on how to do this.
  1235.  
  1236. SYMPTOM 2: GusDelay complains that Virtual DMA Services (VDS) are detected.
  1237.  
  1238. SOLUTION 2: If GusDelay detects VDS it assumes that a protected mode memory 
  1239. manager is installed.  This version of GusDelay is not compatible with such 
  1240. memory managers and will refuse to run.  To use GusDelay, you must boot your 
  1241. PC without a protected mode memory manager.  See the DOS documentation and 
  1242. the memory manager documentation for instructions on disabling your memory 
  1243. manager.  Common memory managers that fall into this category are EMM386, 
  1244. QEMM, and 386MAX.
  1245.  
  1246. SYMPTOM 3: GusDelay hangs the PC after starting - even Ctrl-Alt-Delete won't
  1247. reboot - but numbers in the upper right corner seems to be fluctuating.
  1248.  
  1249. SYMPTOM 4: GusDelay starts OK, but after a short while it produces a "Stack 
  1250. overflow" error and the system is halted.
  1251.  
  1252. SOLUTIONS 3 & 4: I have seen these problems on slower computers and I'm 
  1253. pretty sure it's due to the interrupt latency time being too long, 
  1254. relatively speaking, compared to the actual interrupt service time.  By 
  1255. using the "-w <#>" option (see the "Extra wait factor" section of "Command 
  1256. Line Reference" chapter), you can force GusDelay to increase the number of 
  1257. samples transferred per interrupt and therefore give the PC more time 
  1258. between interrupts to "catch its breath".  A method does exist for 
  1259. calculating the optimal value for "<#>", but it is beyond the scope of this 
  1260. document.  The easiest way to determine the best value is by experimenting 
  1261. with different values.  Start with "-w 1" and work your way up by steps of 
  1262. one until you find a value that works.  In other words, if "-w 1" doesn't 
  1263. work, try "-w 2" and then "-w 3" until it works.  If you get up to "-w 8" 
  1264. and it still doesn't work, please let me know the details of your system and 
  1265. its configuration.  I will do what I can to help you.
  1266.  
  1267. SYMPTOM 5: GusDelay works, but the number in the upper right corner 
  1268. increases until GusDelay spontaneously terminates.  The higher the sample 
  1269. rate, the faster the number increases.  This is especially bad in stereo 
  1270. mode.
  1271.  
  1272. SOLUTION 5: If this occurs, your system is unable to provide the throughput 
  1273. required for steady state operation at the current sample rate.  Use a lower 
  1274. sample rate.
  1275.  
  1276. SYMPTOM 6: GusDelay works, but as soon as I start recording to disk the 
  1277. number in the upper right corner increases until GusDelay spontaneously 
  1278. terminates.  The higher the sample rate, the faster the number increases.  
  1279. This is especially bad in stereo mode.
  1280.  
  1281. SOLUTION 6: If this occurs, your system is unable to provide the throughput 
  1282. required for steady state operation at the current sample rate while 
  1283. recording to disk.  Use the "-d" option (see the "Disk-only mode" section of 
  1284. the "Command Line Reference" chapter) to record to disk at the current 
  1285. sample rate.  This will disable the real-time delay functionality of 
  1286. GusDelay.
  1287.  
  1288. SYMPTOM 7: GusDelay works and when recording to disk the number in the 
  1289. upper right corner is stable (with slight fluctuations), but the recordings 
  1290. end up with slight clicks in them.
  1291.  
  1292. SOLUTION 7: GusDelay uses a special technique to produce click-free 
  1293. recordings, but sometimes when recording AND providing real-time delay there 
  1294. are still clicks in the recording.  Use the "-d" option.  This will disable 
  1295. the real-time delay functionality of GusDelay.
  1296.  
  1297. SYMPTOM 8: GusDelay seems to work OK, but the delayed signals sound very 
  1298. distorted or choppy.
  1299.  
  1300. SOLUTION 8: This is the primary symptom of running GusDelay with a protected 
  1301. mode memory manager loaded.  GusDelay tries to detect when such a memory 
  1302. manager is installed.  Usually the detection works (and GusDelay exits), but 
  1303. you will notice this symptom if the detection fails. For good results, you 
  1304. MUST run GusDelay without ANY protected mode memory manager whatsoever.  
  1305. GusDelay does not use much memory so there is little point in using a memory 
  1306. manager anyway.  If this happens to you please let me know so I can improve 
  1307. the detection routine.
  1308.  
  1309. SYMPTOM 9: GusDelay doesn't work and nothing listed here has helped.
  1310.  
  1311. SOLUTION 9: Let me know the details of your system and its configuration.  I 
  1312. will do what I can to help you get GusDelay working.
  1313.  
  1314. Enjoy!
  1315. Dave
  1316.